MACD 5/MACD 5.bin/workbench/monitory/sysmon/sysmon.doc

Text File | 1995-11-21 | 25KB | 553 lines

$VER: Sysmon.doc 0.2 (19.11.95) © 1995 by Etienne Vogt ([e-mail])


INTRODUCTION

 Sysmon is a system monitoring package based on a shared library and Shell
based support commands. It requires AmigaOS 2.04 or higher.
Main features are :

 - Precise CPU usage timing for all tasks with very low overhead.
 - System message logging daemon like UNIX syslogd (useful for debugging).
 - Safe System shutdown script (useful for BBS's and networked machines).

 This is a public *** BETA *** release, so it's not fully tested. In
particular, I am not sure if it will work on a 68060 based machine. So if
you are the lucky owner of a 68060 based amiga, please test this software
and report the resulting behaviour back to me. My E-Mail address is listed
in this file.
 Sysmon has been successfully tested on the following configurations :

 - A500 68000 ECS, 1 Mb Chip 1.5 Mb Slow 2 Mb Fast , OS 3.1
   20 Mb IDE-XT + 170 Mb SCSI HDs
 - A3000 68030 ECS, 2 Mb Chip 8 Mb Fast , OS 3.1
   100 Mb + 1 Gb SCSI HDs
 - A500 68040(PP&S) ECS , 1 Mb Chip 2 Mb Fast16 8 Mb Fast32 , OS 2.04
   50 Mb SCSI HD
 - A4000 68040 AGA, 2 Mb Chip 8 Mb Fast , OS 3.0
   250 Mb IDE + 1 Gb SCSI-2 HDs
 - A1200 68EC020/68882 AGA, 2 Mb Chip 5 Mb Fast , OS 3.0
   60 Mb IDE + 100 Mb SCSI HDs

 This software is intended for experienced users. In particular, there
are no GUI tools available yet; so if you are a mouse-maniac user that
don't like typing Shell commands or editing ASCII configuration files,
I'm afraid that this software is not for you.


DISTRIBUTION

 Sysmon is Freely Distributable Copyrighted Software (FreeWare).

 It may be freely copied as long as it is kept intact. However, the support
commands that do not require sysmon.library may be distributed separately.
(see the OTHER COMMANDS section below).

 It may not be sold under any guise. I don't want others to make money out
of my work. Distribution MUST BE FREE, except for media costs plus a token
amount covering only shipping and handling.

 Authors of FreeWare may freely use the sysmon.library in their software.
Authors of ShareWare may use the library at the cost of giving me a free
registration (this includes upgrades as long as the software continues
to use the library). Authors of commercial packages MUST obtain a written
license agreement from me before selling software using the library.

 Fred Fish is explicitely allowed to include this package in his AmigaLibDisk
collection (either on floppy disk or on CD-ROM), as is the aminet group for
their Aminet CD-ROM.

 Usage and Distribution of Sysmon and sysmon.library is STRICTLY FORBIDDEN to:
  - Anyone affiliated with the french society FRANCE-FESTIVAL-DISTRIBUTION
    (especially Serge Hammouche).
  - Anyone affiliated with MICROSOFT CORPORATION or its subsidiaries.


DISCLAIMER

 This software is provided "as is" without any warranty, either expressed or
implied. By using this software, you accept the entire risk as to its quality
and performance.
 Especially, as this software patches some private system functions, it can
not be guaranteed that it will continue to work with future operating system
versions, and it will certainly not work as is on a PowerPC based Amiga.


CONTACTING THE AUTHOR

 I can be reached by E-Mail at the following address : [e-mail]

 Bug reports must include the complete hardware and software configuration,
including any third party software that was running in the background.

 If you have any question or suggestion about this software, feel free to
send me E-Mail.


ARCHIVE CONTENTS

Original  Packed Ratio    Date     Time    Name
-------- ------- ----- --------- --------  -------------
    1568     942 39.9% 20-Nov-95 19:51:10  Sysmon/c/Freeze
     672     495 26.3% 20-Nov-95 19:55:40  Sysmon/c/Halt
     784     581 25.8% 20-Nov-95 19:53:38  Sysmon/c/Request
    1436    1005 30.0% 20-Nov-95 19:49:22  Sysmon/c/RunBackground
    6520    4238 35.0% 04-Nov-95 17:07:08  Sysmon/c/ShowSys
    3504    2117 39.5% 20-Nov-95 19:47:32  Sysmon/c/StartSM
     772     560 27.4% 20-Nov-95 19:57:14  Sysmon/c/SysLog
   20208   11718 42.0% 05-Nov-95 16:22:34  Sysmon/c/sysmon
    9192    5922 35.5% 19-Nov-95 00:57:22  Sysmon/c/Timer
    1580     944 40.2% 20-Nov-95 19:58:38  Sysmon/c/UnFreeze
    1900    1353 28.7% 20-Nov-95 20:00:08  Sysmon/c/UnMount
     808     573 29.0% 20-Nov-95 20:01:26  Sysmon/c/ValidateWait
   11629    3598 69.0% 05-Nov-95 17:04:02  Sysmon/docs/sysmon_lib.doc
    6137    2419 60.5% 19-Nov-95 20:05:42  Sysmon/include/sysmon.h
    5853    2409 58.8% 19-Nov-95 22:28:06  Sysmon/include/sysmon.i
     826     237 71.3% 08-Oct-95 18:07:22  Sysmon/include/sysmon_pragmas.h
     732     377 48.4% 08-Oct-95 18:05:56  Sysmon/include/sysmon_protos.h
    5156    3270 36.5% 04-Nov-95 16:15:46  Sysmon/libs/sysmon.library
     937     521 44.3% 02-Nov-95 00:14:08  Sysmon/s/Shutdown
     241     194 19.5% 19-Nov-95 15:01:40  Sysmon/s/Sysmon.config
    2787    1155 58.5% 20-Nov-95 19:48:32  Sysmon/src/Freeze.c
    2310    1027 55.5% 20-Nov-95 19:49:24  Sysmon/src/Halt.c
    2519    1164 53.7% 20-Nov-95 19:49:58  Sysmon/src/Request.c
    3150    1338 57.5% 20-Nov-95 19:47:04  Sysmon/src/RunBackground.c
   10922    3483 68.1% 04-Nov-95 17:03:56  Sysmon/src/ShowSys.c
    7638    2785 63.5% 20-Nov-95 19:45:38  Sysmon/src/StartSM.c
    2673    1122 58.0% 20-Nov-95 19:50:40  Sysmon/src/SysLog.c
    4829    1690 65.0% 19-Nov-95 00:56:12  Sysmon/src/Timer.c
    2809    1153 58.9% 20-Nov-95 19:52:18  Sysmon/src/UnFreeze.c
    6700    2332 65.1% 20-Nov-95 19:52:50  Sysmon/src/UnMount.c
    2740    1204 56.0% 20-Nov-95 19:53:10  Sysmon/src/ValidateWait.c
   25481    9847 61.3% 21-Nov-95 10:50:08  Sysmon/sysmon.doc
-------- ------- ----- --------- --------
  155013   71773 53.6% 21-Nov-95 10:51:00   32 files


INSTALLATION

 - Copy the file 'libs/sysmon.library' to your LIBS: directory.

 - Copy the support commands in the 'c/' sub-directory to C: .

 - Copy the files in the 's/' sub-directory to S: .

 - You may also copy the files in the 'docs/' and 'include/' subdirectories
   wherever you like.

 - Load S:Startup-Sequence in your favorite editor. Locate the line with
   'SetPatch' in it. Add a line just after it saying 'C:StartSM'. Save the
   modified Startup-Sequence.

 - Wait for disk activity to finish, then reboot your Amiga. Sysmon will
   then be started with the default configuration.

 - After bootup, open a shell and type 'showsys'. You should then get a listing
   of all tasks in the system, like this :

   AmigaOS 40.63             05-Nov-95   19:34:37   UpTime :   0 04:45:06
   Address  Name                           State  Pri  CPU [68000]    Type
   0020F700 DH0                            WAIT    10  0 00:00:20.761 Process
   0029E200 Workbench (Workbench)          WAIT     1  0 00:01:38.599 Cli 4
   0021B918 DH2                            WAIT    10  0 00:00:37.442 Process
   002A7628 Active                         WAIT    21  0 00:00:31.385 Process
   00267930 « ConClip »                    WAIT     0  0 00:00:00.002 Process
   00217138 SH0                            WAIT    10  0 00:00:02.803 Process
   00223A3C trackdisk.device               WAIT     5  0 00:00:25.848 Task
   0020703A input.device                   WAIT    20  0 00:22:01.744 Task
   002B9C40 Clock                          WAIT     0  0 00:04:03.565 Process
   00254248 « IPrefs »                     WAIT     0  0 00:00:03.761 Process
   002AFE50 Spliner                        WAIT     0  0 00:00:03.037 Process
   0022C758 ramlib                         WAIT     0  0 00:00:00.762 Process
   00228458 DH3                            WAIT    10  0 00:00:02.828 Process
   0020B858 scsi.device                    WAIT    11  0 00:00:15.128 Task
   00214C70 DF0                            WAIT    10  0 00:00:04.401 Process
   00221570 DF1                            WAIT    10  0 00:00:03.449 Process
   00246570 ErrorLog.daemon (ErrorLogD)    WAIT     6  0 00:00:23.148 Cli 0
   0026A978 RexxMaster                     WAIT     4  0 00:00:00.399 Cli 0
   00297E78 CON                            WAIT     5  0 00:02:08.857 Process
   002B1D78 ClickToFront                   WAIT    21  0 00:00:00.194 Process
   0020DA8C trackdisk.device               WAIT     5  0 00:00:35.705 Task
   00241A88 VD0                            WAIT    10  0 00:00:35.972 Process
   0020C490 A590 SCSI handler              WAIT    12  0 00:00:24.504 Task
   002B5890 AppMenuCx                      WAIT     0  0 00:00:00.198 Process
   00285C98 Background CLI (Snap)          WAIT     1  0 00:00:13.573 Cli 2
   0023A4A0 RAM                            WAIT    10  0 00:00:02.588 Process
   002A49A0 AmigaEyes                      READY   -1  0 00:10:44.476 Process
   00223CB0 DH1                            WAIT    10  0 00:00:07.265 Process
   00296AD0 AmigaShell_3 (showsys)         RUN      0  0 00:06:02.147 Cli 3
   002339D8 Sysmon.server                  WAIT     3  0 00:00:00.106 Process
   0020B2F8 console.device                 WAIT     5  0 00:00:00.400 Task


CONFIGURATION

 The configuration file is used to set up various parameters of operations.
It is usually located in the S: directory. If you want to put it somewhere
else, you have to add the complete path to the file as argument to the
StartSM command in the Startup-Sequence.

 The configuration parameters currently available are :

 - LOGFILE :
   This parameters sets up the name of the file used for the system message
   logging facility. Currently all messages go into a single file. You should
   place this file on a hard disk partition with sufficent free space available.
   The default file name is S:Sysmon.log

 - LOGWINDOW :
   This sets up the window specifications for syslog messages that are serious
   enough to be displayed in a window. You can also redirect them somewhere
   else like an AUX: serial terminal or even a file, but you must be aware
   that this 'file' is not closed after each message like the log file is.
   The default window specification is CON:20/50/600/80/SysLog/AUTO/CLOSE/WAIT

 - FILEPRI :
   Sets up the higher priority level of messages that will be logged in the
   log file; low values mean high severity like in UNIX (See the sysmon.h
   include file for the definitions). The default value is 7 (LOG_DEBUG) which
   means that all messages will be logged.

 - WINPRI :
   This is the same as the previous parameter but for the window logging.
   The default value is 4 (LOG_WARN), meaning that messages of class warning
   or more severe will be logged.

 - CONPRI :
   Sets up the higher priority level for logging to a serial port terminal
   (console). The logging is done via the smKPrintf() function which is not
   system friendly (accesses the serial port hardware directly). If you have
   something else than a terminal attached to your serial port (ex. a modem),
   you should leave this parameter to its default value of 0 (LOG_EMERG).
   This means that only system panic messages will be logged; these can not
   be disabled but are not currently used by the sysmon package (and should
   never be used by application or user programs).

 - LOGBUFFERS :
   This sets up the number of preallocated buffers to store syslog messages
   before they can be logged to disk and/or window by the Sysmon.server
   process. If you have a program that generates lots of messages and you
   think you are losing some of them, you should increase the number of
   buffers. The default value is 5.

 - STAMPPERIOD :
   Sets the time period in minutes between time stamping messages written
   to the logfile at priority level 6 (LOG_INFO). You can disable these
   messages by specifying a stamp period or 0. Default value is 60 minutes
   (one message every hour).

 - IDLELED :
   This enables you to monitor the CPU activity using the power LED. If
   IDLELED is set to YES, the system will dim the power LED when the CPU
   is idle and brighten it when a task is running. This can however cause
   interferences with audio output as the power LED also controls the low
   pass audio filter. Default value is NO.


SUPPORT COMMANDS

 These support commands should be installed in your C: directory. They can
only be used from the Shell.

 - StartSM:

   This command loads and initializes the sysmon.library and starts the
  Sysmon.server syslog process. It should be called from your Startup-Sequence
  right after the SetPatch command.

  Usage : StartSM CONF=CONFIGFILE

  CONFIGFILE :  Specifies the path to the configuration file described before.
        It defaults to S:Sysmon.config

 - ShowSys:

   This command will give a list of all the tasks in the system with their
  address, name, state, priority, cumulated CPU usage and type. An example
  of the display generated by this command was given in the INSTALLATION
  section.

  Usage : ShowSys FULL/S

  FULL:    This switch causes the command to also display the allocated stack
    size, signals usage, task flags and total dispatch count for each
    task.

 - Timer:

   This command runs another command as a subprocess and times the command
  execution. It then reports the elapsed time and the CPU time used by the
  command. It is similar to the UNIX 'time' command.

  Usage : Timer COMMAND/F/A

  COMMAND : The command that will be executed and timed.

 - Freeze:

   This command will suspend a given task by putting it in the FROZEN state.
  It uses the sysmon.library function smFreeze(). (see sysmon_lib.doc for
  further details). This can be useful to stop a looping task that is eating
  away all the CPU time available. Be careful though to not freeze system
  tasks or the whole machine may hang.
   The frozen task can be resurrected by the UnFreeze command.

  Usage : Freeze TASK,ADDR=ADDRESS/K

  TASK:    The name of the task to be frozen. If it is not unique, the first task
    found in the system lists will be frozen.
  ADDRESS: You can alternatively to the name, specify the hexadecimal address
       of the task as displayed by ShowSys.

 - UnFreeze:

   This command will bring a previously frozen task back to life. Is uses the
  sysmon.library function smUnFreeze(). (see sysmon_lib.doc for further details).

  Usage : UnFreeze TASK,ADDR=ADDRESS/K

  TASK:    The name of the task to be unfrozen. If it is not unique, the first task
    found in the frozen list will be unfrozen.
  ADDRESS: You can alternatively to the name, specify the hexadecimal address
       of the task as displayed by ShowSys.

 - Halt:

   This command will halt the system by displaying a guru-like deadend alert.
  It uses the sysmon.library function smHalt(). (see sysmon_lib.doc for further
  details). It is used by the shutdown script and is not intended to be called
  directly.

  Usage : Halt REBOOT/S,REKICK/S

  REBOOT : This switch bypasses the alert display and causes the system to
       reboot immediately.
  REKICK : This switch forces MMU-softkicked machines like the early A3000s
       to reload the kickstart file when rebooting.

 - SysLog:

   This command can be used to generate syslog messages from the Shell.

  Usage : MESSAGE/A,LEVEL/K/N,NOHEAD/S,NOWIN/S,NOFILE/S

  MESSAGE : The message text body which must be inserted between double quotes
        if it contains spaces. The message length is limited to
        SM_MAXLOGCHARS bytes (currently 256).
  LEVEL :   The priority level of the message in numeric form (see sysmon.h)
        Do not use the LOG_EMERG (0) and LOG_ALERT (1) values without
        good reasons.
  NOHEAD :  This switch suppresses the header that is normally prepended to
        each message. This allows you to split a single long message in
        smaller parts.
  NOWIN :   Do not log this message to the log window regardless of priority
        settings.
  NOFILE :  Do not log this message to the log file regardless of priority
        settings.


OTHER COMMANDS

 These commands do not depend on sysmon.library and thus are not to be
considered part of the sysmon package, so they can be distributed separately.
I wrote them for my own usage and decided to distribute them with sysmon
because they may be useful to the Amiga community. The UnMount command is
also used by the shutdown script.

 - RunBackground:

   This command starts a command as a detached process. Unlike the standard
  'run' command, it automatically redirects the standard input and output to
  NIL: so the shell can be closed and it also allows you to specify options
  such as the new process priority and stack size.

  Usage : STACK=STACKSIZE/K/N,PRI=PRIORITY/K/N,DELAY/K/N,NOREQ/S,COMMAND/F/A

  STACKSIZE : The size of the stack to allocate for the new process. Defaults
          to the current shell stack size.
  PRIORITY :  The priority to give to the new process. Defaults to the current
          process priority.
  DELAY :     Optional delay after the new process startup and before the
          command returns. This can be used to avoid concurrent accesses
          to a disk.
  NOREQ :     This switch will disable DOS requesters for the newly created
          process. Unfortunately, software error requesters are also
          disabled, so a CPU trap will cause an immediate guru reboot.
  COMMAND :   The command to be executed.

 - UnMount:

   This command will try to unmount a DOS device by sending it an ACTION_DIE
  packet and optionally an ACTION_INHIBIT packet if the ACTION_DIE fails.
  It is used by the shutdown script to stop filesystem accesses before halting
  the system. Note that very few filesystems or handlers currently implement
  the ACTION_DIE packet (An exception is the CrossDosFileSystem).

  Usage : DEVICE,INHIBIT/S,RETRY/K/N,ALL/S,FREENODE/S

  DEVICE :  The name of the DOS device to unmount.
  INHIBIT : This switch causes the command to send an ACTION_INHIBIT packet
        if the ACTION_DIE fails. ACTION_INHIBIT causes the filesystem
        to appear as 'BUSY' on the workbench screen, like during a format
        or diskcopy.
  RETRY :   The number of retries for the ACTION_INHIBIT if the first one is
        rejected because the filesystem is busy. The retry period is 1
        second and the default number of retries is 10.
  ALL :        Finds all mounted filesystems and tries to unmount them (except
        the RAM-handler). Used by shutdown script.
  FREENODE: This switch causes the command to remove and free the device node
        after the handler has been stopped. Things attached to the device
        node like a file system startup message are not freed. It is similar
        to an 'Assign device: DISMOUNT' command.

 - Request:

   This command enables/disables system requesters in the current shell. This
  can be useful for remote shells or in the User-Startup if you make assigns
  to external disks that may not be always connected.

  Usage : OFF/S,ON/S,WB/S

  OFF :    Disables system requesters in the current shell. Unfortunately, software
    failure requesters are also disabled causing an immediate guru reboot
    in the event of a CPU trap.
  ON :    Enables system requesters on the current screen. For a remote shell,
    enables system requesters on the default public screen.
  WB :    Enables system requesters on the default public screen, usually the
    Workbench screen. This is the default setting at startup.

 - ValidateWait:

   This command waits until the specified volume is validated. If it does not
  become validated within a specified period, it will time out and return an
  error condition to the Shell. It may be a good idea to put a 'ValidateWait SYS:'
  command at the beginning of your Startup-Sequence.

  Usage : DRIVE/A,TIMEOUT/K/N

  DEVICE : The device (or assign) to check for validation.
  TIMEOUT: The amount of time in seconds before timing-out. Defaults to 300
       seconds (5 minutes).


THE SHUTDOWN SCRIPT

 The shutdown script should be placed in your S: directory. It enables you to
perform a safe power down of your system. This is particularly useful if your
machine is connected to a network or runs a BBS.
 You should not edit this script as it may change in a future version of the
Sysmon package. Instead, you should create a User-Shutdown script in S: where
you can put commands to customize the shutdown sequence.

 The sequence of events performed by this script is as follows :

 - First ask the user for confirmation, unless the NOCONF switch was specified
   on the command line. If you enter 'y', the shutdown continues, else it is
   aborted.
 - Set the shell priority to 2, and send a syslog message at level 4 (LOG_WARN).
 - Execute the S:User-Shutdown script if it exists. You can put commands in
   this script to stop commodities or network protocol stacks for example.
   You can also create a Final-Shutdown script in RAM: (via echo or copy
   commands) that will be executed later. All commands used in Final-Shutdown
   must be copied to RAM:
 - Copy all further needed commands to RAM:, reset the search path to RAM:
 - Find and unmount all filesystems except RAM:, using UnMount ALL INHIBIT.
 - Execute the RAM:Final-Shutdown script if created by User-Shutdown.
 - Halt the system via the Halt command. If the REBOOT and/or REKICK options
   were given on the command line, they are passed to the Halt command.
   The REBOOT option will cause the system to reboot immediately. If it is not
   specified, the Halt command will stop all running tasks and display a guru
   like deadend alert saying 'System Shutdown Complete'. You can then safely
   turn the power off or reboot by pressing the left mouse button.

 Usage : Shutdown REBOOT/S,REKICK/S,NOCONF/S

 REBOOT : This switch is passed to the 'Halt' command at the end of the script.
      It bypasses the alert display and causes the system to reboot.
 REKICK : This will force MMU-Softkicked machines like early A3000s to reload
      the kickstart file when rebooting.
 NOCONF : Skip the confirmation question.


THE SYSMON MONITOR

 The sysmon monitor is an interactive shell based program that allows you
to display the system lists and variables and interact with them (not
implemented yet). This program is still under development and more commands
will be implemented in future releases.
 When you type 'sysmon' on the command line, you will get the 'SYSMON>' prompt
back that tells you that the monitor is waiting for commands. You can then
type sysmon commands (not to be confused with the shell-based sysmon support
commands) or exit with the 'EXIT' or 'QUIT' commands.
 You can also specify a command directly on the command line. In this case,
Sysmon will execute the command and exit immediately thereafter.

 All sysmon commands can be abreviated to the minimum number of characters
required to uniquely identify the command. For example, you can type 'sh lib'
instead of 'show libraries'.

 Currently implemented commands are :

 - EXIT:
 - QUIT:
   These commands will exit the sysmon monitor. An end of file (CTRL-\) at the
  'SYSMON>' prompt will do the same.

 - SHOW:
   This command is used to display system lists and variables. The item to
  display is given as first argument to the SHOW command.

  · SHOW TASKS will display all the tasks in the system, in a manner similar
    to the 'ShowSys' support command.

  · SHOW LIBRARIES will display all shared libraries loaded in the system with
    version number, open count, negative and positive sizes of the library node
    and node priority.

  · SHOW DEVICES displays all loaded exec devices

  · SHOW RESOURCES displays the exec Resource list.

  · SHOW RESIDENTS displays the resident module array.

  · SHOW PORTS displays the public Message Port list.

  · SHOW SEMAPHORES displays the public Signal Semaphore list.

  · SHOW MEMORY displays the Memory Header list.

  · SHOW INTERRUPTS displays the Interrupt Nodes installed.

  · SHOW FONTS displays the Text Fonts loaded in memory.

  · SHOW MEMHANDLERS displays the Low Memory Handler list on Amiga OS 3.0+.

  · SHOW LOAD periodically displays the top CPU eating processes and total
    CPU load. The list is updated every 5 seconds and includes upto 16
    processes. A process which takes less than 1 millisecond in an update cycle
    is not displayed; also processes which start and exit within a single cycle
    can not be taken into account.
    Type CTRL-C to exit from this command. An example display from a 'quiet'
    68000 system is showed below :

    UpTime :   0 03:52:16     Update : 00:00:05.010     CPU Load :  18.6 %
    Address  Name                            Load    CPUTime
    00296BB0 AmigaShell_3 (sysmon)            6.9 %  00:00:00.344
    0020703A input.device                     4.5 %  00:00:00.226
    00297F58 CON                              3.1 %  00:00:00.155
    002A4A30 AmigaEyes                        1.8 %  00:00:00.090
    002B9AC8 Clock                            1.5 %  00:00:00.077
    0029E290 Workbench (Workbench)            0.5 %  00:00:00.025
    00224FE4 trackdisk.device                 0.0 %  00:00:00.003
    0020F004 trackdisk.device                 0.0 %  00:00:00.001


WRITING PROGRAMS FOR SYSMON

 You can use the sysmon.library in your own programs. See the DISTRIBUTION
section for legal details. The library contains public functions that can
be used to monitor cpu usage, send syslog messages to the Sysmon.server
process, etc... Read the sysmon_lib.doc autodoc file and the sysmon.h include
file for further information.
 Sources for the support commands are provided as examples.